JavaScript Temporal Duration: Padroneggiare l'Aritmetica e la Formattazione degli Intervalli di Tempo per Applicazioni Globali

La gestione del tempo nello sviluppo software è notoriamente complessa. Dal monitoraggio delle tempistiche di progetto tra continenti alla pianificazione di videoconferenze internazionali, le sfumature degli intervalli di tempo, dei fusi orari e dell'ora legale possono portare rapidamente a bug subdoli ma critici. Per decenni, gli sviluppatori JavaScript hanno lottato con l'oggetto Date integrato, uno strumento che, sebbene funzionale per semplici punti data-ora, si rivela inadeguato quando si tratta di aritmetica precisa degli intervalli di tempo e di una gestione del tempo robusta e consapevole a livello globale.

Entra in scena la JavaScript Temporal API – una proposta rivoluzionaria progettata per fornire un'API moderna, robusta e intuitiva per lavorare con date e orari in JavaScript. Tra i suoi nuovi e potenti tipi, Temporal.Duration si distingue come la soluzione definitiva per la gestione degli intervalli di tempo. Questo articolo vi guiderà in un'analisi approfondita di Temporal.Duration, esplorandone le capacità di calcolo, confronto e formattazione intelligente, per garantire che le vostre applicazioni possano gestire il tempo con precisione e chiarezza globali.

Che tu stia costruendo un sistema logistico globale, una piattaforma di trading finanziario o un pianificatore di eventi multizona, comprendere Temporal.Duration è cruciale per eliminare le ambiguità legate al tempo e offrire esperienze utente affidabili e internazionalizzate.

Le Inadeguatezze dell'Oggetto Date di JavaScript per gli Intervalli di Tempo

Prima di celebrare l'arrivo di Temporal.Duration, è essenziale comprendere i limiti dell'oggetto Date esistente, specialmente quando si ha a che fare con intervalli di tempo. L'oggetto Date rappresenta un punto specifico nel tempo, misurato in millisecondi dall'epoca Unix (1 gennaio 1970, UTC). Sebbene possa essere utilizzato per eseguire calcoli aritmetici di base, presenta diversi difetti intrinseci che lo rendono inadatto per una gestione robusta delle durate:

• Mutabilità: Gli oggetti Date sono mutabili. Qualsiasi operazione su un oggetto Date ne modifica lo stato interno, il che può portare a effetti collaterali inaspettati e a bug difficili da tracciare, in particolare in applicazioni complesse o ambienti concorrenti.

              const d = new Date('2023-01-15T10:00:00Z');
  const d2 = d; // d2 ora fa riferimento allo stesso oggetto di d
  d.setHours(d.getHours() + 1);
  
  console.log(d.toISOString());  // 2023-01-15T11:00:00.000Z
  console.log(d2.toISOString()); // 2023-01-15T11:00:00.000Z (anche d2 è cambiato!)
  
              
  
                
                  Copy
                
              
            

• Mancanza di un Concetto di Durata: L'oggetto Date non ha un concetto diretto di "durata" o "periodo". Calcolare la differenza tra due date restituisce un numero di millisecondi, che deve poi essere convertito manualmente in anni, mesi, giorni, ecc. Questa conversione manuale è soggetta a errori, specialmente quando si ha a che fare con mesi di lunghezza variabile o anni bisestili.

              const date1 = new Date('2023-01-01T00:00:00Z');
  const date2 = new Date('2023-03-01T00:00:00Z');
  
  const diffMs = date2.getTime() - date1.getTime();
  
  // Quanti mesi sono? E gli anni bisestili?
  // (diffMs / (1000 * 60 * 60 * 24 * 30)) è, nella migliore delle ipotesi, un'approssimazione.
  console.log(`Difference in milliseconds: ${diffMs}`);
  console.log(`Approximate days: ${diffMs / (1000 * 60 * 60 * 24)}`); // Funziona per i giorni, ma non è robusto per mesi/anni
  
              
  
                
                  Copy
                
              
            

• Ambiguità del Fuso Orario: Gli oggetti Date spesso confondono l'ora locale con l'UTC. Sebbene memorizzino internamente i millisecondi UTC, i loro metodi operano frequentemente sul fuso orario locale del sistema per impostazione predefinita, portando a confusione e incongruenze quando si lavora con sistemi distribuiti o utenti internazionali.
• Sfide dell'Ora Legale (DST): Le transizioni dell'ora legale possono far sì che i giorni durino 23 o 25 ore. Semplici calcoli aritmetici (ad esempio, aggiungere 24 ore a una data) potrebbero non portare sempre al giorno di calendario successivo, causando calcoli errati quando si presume che un "giorno" sia un periodo fisso di 24 ore.

Queste limitazioni hanno storicamente costretto gli sviluppatori a fare affidamento su librerie di terze parti come Moment.js o date-fns, o a scrivere codice personalizzato complesso e soggetto a errori per gestire correttamente gli intervalli di tempo. Temporal mira a portare queste capacità nativamente in JavaScript.

Introduzione a JavaScript Temporal: Un Approccio Moderno al Tempo

L'API Temporal è un nuovo e completo oggetto globale in JavaScript, progettato per essere un sostituto moderno del vecchio oggetto Date. I suoi principi fondamentali sono l'immutabilità, la gestione esplicita dei fusi orari e una chiara separazione delle responsabilità tra i diversi concetti temporali. Temporal introduce diverse nuove classi, ognuna delle quali rappresenta un aspetto distinto del tempo:

• Temporal.Instant: Un punto specifico e non ambiguo nel tempo, indipendente da qualsiasi calendario o fuso orario (simile a un timestamp Unix, ma con precisione al nanosecondo).
• Temporal.ZonedDateTime: Un punto specifico nel tempo in un particolare calendario e fuso orario. Questa è la rappresentazione più completa di una data e un'ora specifiche per un utente.
• Temporal.PlainDate: Una data del calendario (anno, mese, giorno) senza un orario o un fuso orario.
• Temporal.PlainTime: Un'ora dell'orologio (ora, minuto, secondo, ecc.) senza una data o un fuso orario.
• Temporal.PlainDateTime: Una data del calendario e un'ora dell'orologio insieme, senza un fuso orario.
• Temporal.PlainYearMonth: Un anno e un mese specifici in un sistema di calendario.
• Temporal.PlainMonthDay: Un mese e un giorno specifici in un sistema di calendario.
• Temporal.Duration: Una durata di tempo con segno, come "5 ore e 30 minuti" o "2 giorni". Questo è il nostro focus per questa guida.

Tutti gli oggetti Temporal sono immutabili, il che significa che operazioni come l'aggiunta o la sottrazione di tempo creano nuovi oggetti invece di modificare quelli esistenti, migliorando la prevedibilità e riducendo i bug.

Comprendere Temporal.Duration

Un Temporal.Duration rappresenta una durata di tempo. Fondamentalmente, è indipendente da un punto di inizio o di fine specifico. È semplicemente "quanto tempo" è trascorso o trascorrerà. Può essere composto da anni, mesi, settimane, giorni, ore, minuti, secondi, millisecondi, microsecondi e nanosecondi. Ogni componente è un intero e può essere positivo o negativo.

Ad esempio, "2 ore e 30 minuti" è una durata. "Il periodo dal 1° gennaio al 1° marzo" è una durata tra due punti specifici, che può essere *rappresentata* da un Temporal.Duration, ma la Duration stessa è solo l'intervallo.

Creare una Durata

Ci sono diversi modi semplici per creare oggetti Temporal.Duration:

1. Usare il Costruttore

Il costruttore consente di specificare direttamente ogni componente. Notare che gli argomenti sono ordinati dall'unità più grande (anni) alla più piccola (nanosecondi).

            // new Temporal.Duration(anni, mesi, settimane, giorni, ore, minuti, secondi, millisecondi, microsecondi, nanosecondi)

// Una durata di 2 ore e 30 minuti
const duration1 = new Temporal.Duration(0, 0, 0, 0, 2, 30, 0, 0, 0, 0);
console.log(duration1.toString()); // P2H30M

// Una durata di 1 anno, 2 mesi, 3 giorni
const duration2 = new Temporal.Duration(1, 2, 0, 3);
console.log(duration2.toString()); // P1Y2M3D

// Una durata di -5 giorni
const duration3 = new Temporal.Duration(0, 0, 0, -5);
console.log(duration3.toString()); // P-5D

            

              
                Copy
              
            
          

2. Usare Temporal.Duration.from() con un Oggetto

Questo è spesso il modo più leggibile per creare durate, permettendoti di specificare solo i componenti di cui hai bisogno.

            // Durata di 1,5 ore
const halfHourDuration = Temporal.Duration.from({ hours: 1, minutes: 30 });
console.log(halfHourDuration.toString()); // P1H30M

// Durata di 7 giorni (1 settimana)
const oneWeekDuration = Temporal.Duration.from({ days: 7 });
console.log(oneWeekDuration.toString());  // P7D

// Durata con secondi frazionari (es. 2,5 secondi)
const twoPointFiveSeconds = Temporal.Duration.from({ seconds: 2, milliseconds: 500 });
console.log(twoPointFiveSeconds.toString()); // PT2.5S

// Durata negativa
const negativeDuration = Temporal.Duration.from({ minutes: -45 });
console.log(negativeDuration.toString()); // PT-45M

            

              
                Copy
              
            
          

3. Usare Temporal.Duration.from() con una Stringa ISO 8601

Temporal sfrutta il formato di durata ISO 8601, che è uno standard per rappresentare le durate. Questo è eccellente per analizzare durate provenienti da fonti di dati esterne.

Il formato generalmente si presenta come P[anni]Y[mesi]M[settimane]W[giorni]DT[ore]H[minuti]M[secondi]S. La T separa i componenti della data da quelli dell'ora.

            // 1 anno, 2 mesi, 3 giorni
const isoDuration1 = Temporal.Duration.from('P1Y2M3D');
console.log(isoDuration1.toString()); // P1Y2M3D

// 4 ore, 5 minuti, 6 secondi
const isoDuration2 = Temporal.Duration.from('PT4H5M6S');
console.log(isoDuration2.toString()); // PT4H5M6S

// Una durata combinata
const isoDuration3 = Temporal.Duration.from('P7DT12H30M');
console.log(isoDuration3.toString()); // P7DT12H30M

// Sono supportati anche i secondi frazionari
const isoDuration4 = Temporal.Duration.from('PT1.5S');
console.log(isoDuration4.toString()); // PT1.5S

            

              
                Copy
              
            
          

Eseguire Calcoli Aritmetici con le Durate

Il vero potere di Temporal.Duration risiede nelle sue capacità aritmetiche. È possibile sommare, sottrarre, moltiplicare e dividere le durate, e anche aggiungerle/sottrarle ad altri tipi data-ora di Temporal. Tutte le operazioni restituiscono nuovi oggetti Temporal.Duration a causa dell'immutabilità.

Sommare le Durate

Il metodo add() combina due durate.

            const sprintDuration = Temporal.Duration.from({ weeks: 2 });
const bufferDuration = Temporal.Duration.from({ days: 3 });

const totalProjectTime = sprintDuration.add(bufferDuration);
console.log(totalProjectTime.toString()); // P2W3D (o P17D se normalizzato in seguito)

// Aggiungere una durata negativa equivale a una sottrazione
const result = Temporal.Duration.from({ hours: 5 }).add({ hours: -2 });
console.log(result.toString()); // PT3H

            

              
                Copy
              
            
          

È anche possibile aggiungere una durata a qualsiasi oggetto data/ora di Temporal. È qui che avviene la magia, poiché Temporal gestisce correttamente i cambi di fuso orario e le transizioni dell'ora legale quando pertinente.

            const projectStart = Temporal.PlainDateTime.from('2023-10-26T09:00:00');
const projectDuration = Temporal.Duration.from({ days: 10, hours: 4 });

const projectEnd = projectStart.add(projectDuration);
console.log(projectEnd.toString()); // 2023-11-05T13:00:00

// Con uno ZonedDateTime, le regole del fuso orario sono applicate correttamente
const meetingStartUTC = Temporal.ZonedDateTime.from('2024-03-09T14:00:00[UTC]');
const meetingDuration = Temporal.Duration.from({ hours: 1, minutes: 45 });

const meetingEndUTC = meetingStartUTC.add(meetingDuration);
console.log(meetingEndUTC.toString()); // 2024-03-09T15:45:00+00:00[UTC]

// Esempio che attraversa il limite dell'ora legale (assumendo che 'Europe/Berlin' cambi alle 03:00 del 31-03-2024)
const springForwardStart = Temporal.ZonedDateTime.from('2024-03-30T22:00:00[Europe/Berlin]');
const twentyFourHours = Temporal.Duration.from({ hours: 24 });

const nextDay = springForwardStart.add(twentyFourHours); // Aggiunge 24 ore effettive
console.log(springForwardStart.toString()); // 2024-03-30T22:00:00+01:00[Europe/Berlin]
console.log(nextDay.toString());          // 2024-03-31T23:00:00+02:00[Europe/Berlin] (L'ora locale ha saltato un'ora)

            

              
                Copy
              
            
          

Notare come l'aggiunta di 24 ore a 2024-03-30T22:00:00 a Berlino (che è UTC+1) risulti in 2024-03-31T23:00:00 (ora UTC+2). L'orologio è avanzato di un'ora, quindi l'ora dell'orologio è un'ora più tardi nella stessa data rispetto all'ora dell'orologio di partenza. Ciò dimostra con precisione la consapevolezza di Temporal riguardo al fuso orario e all'ora legale quando esegue calcoli su `ZonedDateTime`.

Sottrarre le Durate

Il metodo subtract() funziona in modo simile a add(), ma rimuove tempo.

            const deadlineDuration = Temporal.Duration.from({ days: 30 });
const gracePeriod = Temporal.Duration.from({ days: 5 });

const effectiveDeadline = deadlineDuration.subtract(gracePeriod);
console.log(effectiveDeadline.toString()); // P25D

const taskEnd = Temporal.PlainDateTime.from('2023-12-01T17:00:00');
const taskDuration = Temporal.Duration.from({ hours: 8, minutes: 30 });

const taskStart = taskEnd.subtract(taskDuration);
console.log(taskStart.toString()); // 2023-12-01T08:30:00

            

              
                Copy
              
            
          

Moltiplicare e Dividere le Durate

I metodi multiply() e divide() scalano i componenti di una durata per un dato fattore. Ciò è utile per scenari come il calcolo del tempo totale per più iterazioni di un'attività.

            const trainingSession = Temporal.Duration.from({ minutes: 45 });
const weeklyTraining = trainingSession.multiply(5); // Cinque sessioni a settimana
console.log(weeklyTraining.toString()); // PT225M

const totalProjectHours = Temporal.Duration.from({ hours: 160 });
const teamMembers = 4;

const hoursPerMember = totalProjectHours.divide(teamMembers);
console.log(hoursPerMember.toString()); // PT40H

            

              
                Copy
              
            
          

Negare le Durate

Il metodo negate() inverte il segno di tutti i componenti di una durata. Una durata positiva diventa negativa e viceversa.

            const delayDuration = Temporal.Duration.from({ hours: 3 });
const advanceDuration = delayDuration.negate();

console.log(delayDuration.toString());   // PT3H
console.log(advanceDuration.toString()); // PT-3H

            

              
                Copy
              
            
          

Valore Assoluto delle Durate

Il metodo abs() restituisce un nuovo Temporal.Duration con tutti i componenti resi positivi, fornendo di fatto la magnitudine della durata indipendentemente dal suo segno.

            const negativeDelay = Temporal.Duration.from({ minutes: -60 });
const positiveDuration = negativeDelay.abs();

console.log(negativeDelay.toString());  // PT-60M
console.log(positiveDuration.toString()); // PT60M

            

              
                Copy
              
            
          

Confrontare e Normalizzare le Durate

Confrontare le durate può essere complicato, specialmente quando sono coinvolte unità diverse (ad esempio, 1 mese è uguale a 30 giorni?). Temporal fornisce strumenti sia per il confronto che per la normalizzazione per gestire queste complessità.

Confrontare le Durate con compare()

Il metodo statico Temporal.Duration.compare(duration1, duration2, options) restituisce:

• -1 se duration1 è minore di duration2
• 0 se duration1 è uguale a duration2
• 1 se duration1 è maggiore di duration2

È fondamentale notare che, quando si confrontano durate che includono unità di lunghezza variabile come anni, mesi o settimane, è spesso necessario fornire un'opzione relativeTo. Questo parametro è un oggetto `Temporal.ZonedDateTime` o `Temporal.PlainDateTime` che fornisce il contesto su come interpretare queste unità (ad esempio, quanti giorni ci sono in un mese o anno specifico).

            const oneHour = Temporal.Duration.from({ hours: 1 });
const sixtyMinutes = Temporal.Duration.from({ minutes: 60 });

console.log(Temporal.Duration.compare(oneHour, sixtyMinutes)); // 0 (Sono equivalenti)

const oneMonth = Temporal.Duration.from({ months: 1 });
const thirtyDays = Temporal.Duration.from({ days: 30 });

// Senza relativeTo, i confronti di mesi/anni sono difficili
console.log(Temporal.Duration.compare(oneMonth, thirtyDays)); // 0 (Temporal fa un'ipotesi ragionevole senza contesto, spesso basata sulla media)

// Con relativeTo, il confronto è preciso in base al calendario del contesto
const startOfJanuary = Temporal.PlainDate.from('2023-01-01');
const endOfFebruaryLeap = Temporal.PlainDate.from('2024-02-01'); // Anno bisestile

// A gennaio 2023, 1 mese corrisponde a 31 giorni
const comparisonJan = Temporal.Duration.compare(oneMonth, thirtyDays, { relativeTo: startOfJanuary });
console.log(`1 mese vs 30 giorni a Gen 2023: ${comparisonJan}`); // 1 (1 mese > 30 giorni)

// A febbraio 2024 (anno bisestile), 1 mese corrisponde a 29 giorni
const comparisonFeb = Temporal.Duration.compare(oneMonth, thirtyDays, { relativeTo: endOfFebruaryLeap });
console.log(`1 mese vs 30 giorni a Feb 2024: ${comparisonFeb}`); // -1 (1 mese < 30 giorni)

            

              
                Copy
              
            
          

Normalizzare le Durate con normalize() e round()

Le durate possono essere rappresentate in molti modi (ad esempio, 90 minuti o 1 ora e 30 minuti). La normalizzazione e l'arrotondamento aiutano a standardizzare queste rappresentazioni per coerenza e visualizzazione.

normalize()

Il metodo normalize() semplifica i componenti della durata dove possibile (ad esempio, 60 minuti diventano 1 ora, 24 ore diventano 1 giorno, a condizione che il contesto `relativeTo` lo consenta se sono coinvolti mesi/anni).

            const longMinutes = Temporal.Duration.from({ minutes: 90 });
console.log(longMinutes.toString()); // PT90M
console.log(longMinutes.normalize().toString()); // PT1H30M

const multipleDays = Temporal.Duration.from({ hours: 48 });
console.log(multipleDays.toString()); // PT48H
console.log(multipleDays.normalize().toString()); // P2D

            

              
                Copy
              
            
          

round()

Il metodo round() è più potente per trasformare e arrotondare le durate a unità specifiche. Accetta un oggetto di opzioni con:

• largestUnit: L'unità più grande da includere nell'output (es. 'years', 'days', 'hours').
• smallestUnit: L'unità più piccola da includere nell'output (es. 'minutes', 'seconds', 'milliseconds').
• roundingIncrement: Un intero per cui arrotondare l'unità più piccola (es. 5 per arrotondare ai 5 minuti più vicini).
• roundingMode: Come gestire i pareggi (es. 'halfExpand', 'trunc', 'ceil', 'floor').
• relativeTo: Richiesto per arrotondare durate contenenti anni, mesi o settimane.

            const complexDuration = Temporal.Duration.from({ hours: 2, minutes: 45, seconds: 30 });

// Arrotonda all'ora più vicina
const roundedToHours = complexDuration.round({ smallestUnit: 'hour' });
console.log(roundedToHours.toString()); // PT3H

// Arrotonda ai 30 minuti più vicini, mantenendo le ore
const roundedTo30Minutes = complexDuration.round({
  largestUnit: 'hour',
  smallestUnit: 'minute',
  roundingIncrement: 30
});
console.log(roundedTo30Minutes.toString()); // PT3H

const preciseDuration = Temporal.Duration.from({ minutes: 123, seconds: 45 });

// Visualizza come ore e minuti
const formattedDuration = preciseDuration.round({ largestUnit: 'hour', smallestUnit: 'minute' });
console.log(formattedDuration.toString()); // PT2H4M

// L'arrotondamento con mesi/anni richiede relativeTo
const longTermDuration = Temporal.Duration.from({ months: 1, days: 10 });
const referenceDate = Temporal.PlainDate.from('2023-01-15');

// Arrotonda ai mesi, relativo a una data
const roundedToMonths = longTermDuration.round({ largestUnit: 'month', smallestUnit: 'month', relativeTo: referenceDate });
console.log(roundedToMonths.toString()); // P1M

            

              
                Copy
              
            
          

Calcolare le Durate tra Oggetti Temporal

Uno degli usi più frequenti delle durate è il calcolo dell'intervallo di tempo tra due punti specifici nel tempo. Temporal fornisce i metodi until() e since() sui suoi oggetti data-ora per questo scopo.

Metodo until()

Il metodo until() calcola la durata dall'oggetto ricevente all'oggetto argomento. È inclusivo del punto di inizio ed esclusivo del punto di fine. Accetta un oggetto di opzioni simile a round() per specificare le unità desiderate e il comportamento di arrotondamento.

            const startDate = Temporal.PlainDate.from('2023-01-01');
const endDate = Temporal.PlainDate.from('2023-03-15');

// Durata nelle unità più grandi possibili (mesi, poi giorni)
const projectLength = startDate.until(endDate);
console.log(projectLength.toString()); // P2M14D

// Durata puramente in giorni
const totalDays = startDate.until(endDate, { largestUnit: 'day' });
console.log(totalDays.toString()); // P73D

// Durata tra due orari specifici, rispettando i fusi orari
const meetingStart = Temporal.ZonedDateTime.from('2024-07-20T10:00:00[America/New_York]');
const meetingEnd = Temporal.ZonedDateTime.from('2024-07-20T11:30:00[America/New_York]');

const elapsedMeetingTime = meetingStart.until(meetingEnd, { largestUnit: 'hour', smallestUnit: 'minute' });
console.log(elapsedMeetingTime.toString()); // PT1H30M

// Durata tra fusi orari diversi (da NYC a Londra)
const nyStartTime = Temporal.ZonedDateTime.from('2024-08-01T09:00:00[America/New_York]');
const londonEndTime = Temporal.ZonedDateTime.from('2024-08-01T17:00:00[Europe/London]');

const travelDuration = nyStartTime.until(londonEndTime);
console.log(travelDuration.toString()); // PT13H (Tempo effettivo trascorso, non differenza di orario)

            

              
                Copy
              
            
          

L'ultimo esempio è particolarmente illuminante. Anche se New York è 5 ore indietro rispetto a Londra, e gli orari dell'orologio sono le 9:00 e le 17:00 dello stesso giorno, il metodo until() calcola correttamente il tempo effettivo trascorso di 13 ore. Questo perché ZonedDateTime gestisce implicitamente la differenza di fuso orario.

Metodo since()

Il metodo since() è l'inverso di until(). Calcola la durata dall'oggetto argomento all'oggetto ricevente, risultando in una durata negativa se l'argomento è nel futuro rispetto al ricevente.

            const currentDateTime = Temporal.ZonedDateTime.from('2024-06-15T12:00:00[Europe/Paris]');
const historicEvent = Temporal.ZonedDateTime.from('2024-01-01T00:00:00[Europe/Paris]');

const timeSinceEvent = currentDateTime.since(historicEvent, { largestUnit: 'month', smallestUnit: 'day' });
console.log(timeSinceEvent.toString()); // P5M14D

const futureDate = Temporal.PlainDate.from('2025-01-01');
const pastDate = Temporal.PlainDate.from('2024-01-01');

const durationFromFuture = pastDate.since(futureDate);
console.log(durationFromFuture.toString()); // P-1Y

            

              
                Copy
              
            
          

Gestire Unità Diverse e Arrotondamenti per le Durate Calcolate

Quando si calcolano le durate, è spesso necessario specificare `largestUnit` e `smallestUnit` per ottenere una rappresentazione leggibile dall'uomo, specialmente per l'età, il tempo trascorso o i conti alla rovescia.

            const birthDate = Temporal.PlainDate.from('1990-07-15');
const today = Temporal.PlainDate.from('2024-06-15');

// Calcola l'età in anni, mesi e giorni
const age = birthDate.until(today, { largestUnit: 'year', smallestUnit: 'day' });
console.log(`Età: ${age.years} anni, ${age.months} mesi, ${age.days} giorni`); // Età: 33 anni, 11 mesi, 0 giorni

// Calcola il tempo rimanente per un'attività in ore e minuti
const now = Temporal.Instant.fromEpochSeconds(Date.now() / 1000);
const deadline = Temporal.Instant.from('2024-07-01T09:00:00Z');

const timeLeft = now.until(deadline, { largestUnit: 'hour', smallestUnit: 'minute', roundingMode: 'ceil' });
console.log(`Tempo rimanente: ${timeLeft.hours} ore e ${timeLeft.minutes} minuti.`); // Esempio: Tempo rimanente: 355 ore e 38 minuti.

            

              
                Copy
              
            
          

Formattare le Durate per un Pubblico Globale

Sebbene Temporal.Duration fornisca rappresentazioni programmatiche precise degli intervalli di tempo, non ha un metodo toLocaleString() integrato. Questo è voluto: le durate sono lunghezze di tempo astratte, e la loro visualizzazione può variare notevolmente a seconda del contesto, della locale e del livello di dettaglio desiderato. Tu, come sviluppatore, sei responsabile di presentare le durate in modo intuitivo e comprensibile a livello globale.

Rappresentazione tramite Stringa ISO 8601

Il metodo predefinito toString() di un oggetto Temporal.Duration restituisce la sua rappresentazione in formato stringa ISO 8601. Questo è eccellente per la comunicazione da macchina a macchina, la serializzazione e l'archiviazione, ma raramente per la visualizzazione diretta agli utenti finali.

            const examDuration = Temporal.Duration.from({ hours: 2, minutes: 15 });
console.log(examDuration.toString()); // PT2H15M

const holidayDuration = Temporal.Duration.from({ weeks: 2, days: 3 });
console.log(holidayDuration.toString()); // P2W3D

            

              
                Copy
              
            
          

Formattazione Manuale per Leggibilità e Internazionalizzazione

Per la visualizzazione rivolta all'utente, tipicamente estrarrai i componenti di una durata e li formatterai usando l'interpolazione di stringhe e l'API Intl di JavaScript.

Ecco un esempio di funzione personalizzata che formatta una durata:

            function formatDurationToHumanReadable(duration, locale = 'it-IT') {
  const parts = [];

  // Usare Intl.NumberFormat per la formattazione dei numeri in base alla locale
  const numberFormatter = new Intl.NumberFormat(locale);

  if (duration.years !== 0) {
    parts.push(numberFormatter.format(duration.years) + ' ' + (duration.years === 1 ? 'anno' : 'anni'));
  }
  if (duration.months !== 0) {
    parts.push(numberFormatter.format(duration.months) + ' ' + (duration.months === 1 ? 'mese' : 'mesi'));
  }
  if (duration.weeks !== 0) {
    parts.push(numberFormatter.format(duration.weeks) + ' ' + (duration.weeks === 1 ? 'settimana' : 'settimane'));
  }
  if (duration.days !== 0) {
    parts.push(numberFormatter.format(duration.days) + ' ' + (duration.days === 1 ? 'giorno' : 'giorni'));
  }
  if (duration.hours !== 0) {
    parts.push(numberFormatter.format(duration.hours) + ' ' + (duration.hours === 1 ? 'ora' : 'ore'));
  }
  if (duration.minutes !== 0) {
    parts.push(numberFormatter.format(duration.minutes) + ' ' + (duration.minutes === 1 ? 'minuto' : 'minuti'));
  }
  if (duration.seconds !== 0) {
    // Arrotondare i secondi per la visualizzazione se hanno parti frazionarie
    const roundedSeconds = numberFormatter.format(duration.seconds.toFixed(0)); // O toFixed(1) per un decimale
    parts.push(roundedSeconds + ' ' + (duration.seconds === 1 ? 'secondo' : 'secondi'));
  }

  if (parts.length === 0) {
    // Gestire i casi in cui la durata è zero o molto piccola (es. solo nanosecondi)
    if (duration.milliseconds !== 0 || duration.microseconds !== 0 || duration.nanoseconds !== 0) {
        const totalMs = duration.milliseconds + duration.microseconds / 1000 + duration.nanoseconds / 1_000_000;
        return numberFormatter.format(totalMs.toFixed(2)) + ' millisecondi';
    }
    return '0 secondi';
  }

  // Unire le parti con virgole e 'e' per l'ultima parte (unione base in italiano)
  if (parts.length > 1) {
    const lastPart = parts.pop();
    return parts.join(', ') + ' e ' + lastPart;
  } else {
    return parts[0];
  }
}

const tripDuration = Temporal.Duration.from({ days: 3, hours: 10, minutes: 45 });
console.log(formatDurationToHumanReadable(tripDuration, 'en-US')); // 3 days, 10 hours and 45 minutes
console.log(formatDurationToHumanReadable(tripDuration, 'es-ES')); // 3 días, 10 horas y 45 minutos (example of Intl.NumberFormat)

const meetingReminder = Temporal.Duration.from({ minutes: 5 });
console.log(formatDurationToHumanReadable(meetingReminder, 'en-GB')); // 5 minutes

const microDuration = Temporal.Duration.from({ nanoseconds: 1234567 });
console.log(formatDurationToHumanReadable(microDuration, 'en-US')); // 1.23 milliseconds

            

              
                Copy
              
            
          

Per una gestione più avanzata delle pluralizzazioni e della formattazione di elenchi localizzati, si potrebbe combinare questo approccio con Intl.RelativeTimeFormat o con librerie di templating di stringhe più complesse. La chiave è separare il calcolo della durata (gestito da Temporal) dalla sua presentazione (gestita dalla tua logica di formattazione e da Intl).

Usare Intl.DurationFormat (Futuro/Proposta)

Esiste una proposta TC39 in corso per Intl.DurationFormat, che mira a fornire un modo nativo e consapevole della locale per formattare le durate. Se standardizzata e implementata, semplificherebbe notevolmente la formattazione manuale mostrata sopra, offrendo una soluzione robusta per l'internazionalizzazione direttamente all'interno dell'ecosistema JavaScript.

Funzionerebbe probabilmente in modo simile ad altri oggetti Intl:

            // Questo è ipotetico e basato sullo stato attuale della proposta
// Verificare la compatibilità dei browser prima dell'uso in produzione

/*
const duration = Temporal.Duration.from({ days: 1, hours: 2, minutes: 30 });

const formatter = new Intl.DurationFormat('it-IT', {
  style: 'long',
  years: 'long',
  days: 'long',
  hours: 'long',
  minutes: 'long',
});

console.log(formatter.format(duration)); // "1 giorno, 2 ore, 30 minuti"

const shortFormatter = new Intl.DurationFormat('fr-FR', { style: 'short', hours: 'numeric', minutes: 'numeric' });
console.log(shortFormatter.format(duration)); // "1 j, 2 h, 30 min"
*/

            

              
                Copy
              
            
          

Sebbene non sia ancora disponibile in tutti gli ambienti, tenete d'occhio questa proposta poiché promette di essere la soluzione definitiva per la formattazione globale delle durate in futuro.

Casi d'Uso Pratici e Considerazioni Globali

Temporal.Duration non è solo un miglioramento accademico; risolve problemi del mondo reale in applicazioni che operano attraverso fusi orari e culture diverse.

1. Pianificazione e Gestione di Eventi

Per le piattaforme che gestiscono eventi, conferenze o appuntamenti internazionali, calcolare la durata degli eventi, il tempo rimanente a un evento o la durata di una pausa è fondamentale. Temporal.Duration garantisce che questi calcoli siano accurati indipendentemente dalla posizione dell'utente o dalle regole del fuso orario locale.

            // Calcola il tempo rimanente per un webinar globale
const now = Temporal.ZonedDateTime.from('2024-07-25T10:00:00[Europe/London]'); // Esempio di ora corrente
const webinarStart = Temporal.ZonedDateTime.from('2024-07-26T14:30:00[Asia/Tokyo]');

const timeUntilWebinar = now.until(webinarStart, {
  largestUnit: 'hour',
  smallestUnit: 'minute',
  roundingMode: 'ceil' // Arrotonda per eccesso per garantire che gli utenti non lo perdano
});

console.log(`Il webinar inizia tra ${timeUntilWebinar.hours} ore e ${timeUntilWebinar.minutes} minuti.`);
// L'output sarà accurato in base al tempo effettivo trascorso tra questi due ZonedDateTime.

            

              
                Copy
              
            
          

2. Metriche di Performance e Logging

Misurare il tempo di esecuzione delle operazioni, i tempi di risposta delle API o le durate dei processi batch richiede alta precisione. Temporal.Duration, specialmente se combinato con Temporal.Instant (che offre precisione al nanosecondo), è ideale per questo.

            const startTime = Temporal.Instant.now();

// Simula un'operazione complessa
for (let i = 0; i < 1_000_000; i++) { Math.sqrt(i); }

const endTime = Temporal.Instant.now();

const executionDuration = startTime.until(endTime);

// Formatta in secondi con millisecondi per la visualizzazione
const formattedExecution = executionDuration.round({ smallestUnit: 'millisecond', largestUnit: 'second' });

console.log(`L'operazione ha richiesto ${formattedExecution.seconds}.${String(formattedExecution.milliseconds).padStart(3, '0')} secondi.`);

            

              
                Copy
              
            
          

3. Calcoli Finanziari

In finanza, gli intervalli di tempo precisi sono fondamentali per calcolare interessi, termini di prestito o periodi di investimento. Il numero esatto di giorni, mesi o anni in un periodo deve essere accurato, specialmente quando si ha a che fare con anni bisestili o lunghezze di mesi specifiche.

            const loanStartDate = Temporal.PlainDate.from('2023-04-01');
const loanEndDate = Temporal.PlainDate.from('2028-03-31');

const loanTerm = loanStartDate.until(loanEndDate, { largestUnit: 'year', smallestUnit: 'month' });
console.log(`Durata del prestito: ${loanTerm.years} anni e ${loanTerm.months} mesi.`); // 4 anni e 11 mesi

            

              
                Copy
              
            
          

4. Sfide di Internazionalizzazione Riconsiderate

• Fusi Orari e Ora Legale: Temporal.Duration di per sé è agnostico rispetto al fuso orario; rappresenta una durata fissa di tempo. Tuttavia, quando si aggiunge o si sottrae una Duration a/da uno ZonedDateTime, Temporal applica correttamente le regole del fuso orario, inclusi i cambi dell'ora legale. Ciò garantisce che una "durata di 24 ore" faccia avanzare realmente uno ZonedDateTime di 24 ore effettive, anche se ciò significa attraversare un confine dell'ora legale che rende il giorno *dell'orologio* più corto o più lungo. Questa coerenza è una vittoria importante rispetto a `Date`.
• Variazioni Culturali: Culture diverse esprimono le durate in modi diversi. Sebbene Temporal.Duration fornisca i componenti grezzi (anni, mesi, giorni, ecc.), è tua responsabilità usare le API `Intl` o una logica personalizzata per presentarli in un modo che sia familiare alla locale dell'utente. Ad esempio, alcune culture potrebbero esprimere "1 ora e 30 minuti" come "90 minuti" o usare regole di pluralizzazione diverse.
• Sistemi di Calendario: Temporal supporta anche diversi sistemi di calendario (ad esempio, calendari giapponese, persiano, islamico). Sebbene Duration sia di per sé agnostico rispetto al calendario, quando interagisce con tipi consapevoli del calendario come PlainDate o ZonedDateTime, l'aritmetica rispetta le regole specifiche di quel calendario (ad esempio, il numero di giorni in un mese, le regole dell'anno bisestile all'interno di quel calendario). Questo è cruciale per le applicazioni globali che potrebbero dover visualizzare le date in calendari non gregoriani.

Stato Attuale e Adozione di Temporal

A fine 2023/inizio 2024, la JavaScript Temporal API è una proposta TC39 di Stage 3. Ciò significa che la specifica è in gran parte stabile ed è in fase di implementazione e test in vari motori JavaScript e browser. I principali browser come Chrome, Firefox e Safari stanno lavorando attivamente all'implementazione di Temporal, con flag sperimentali o versioni iniziali già disponibili.

Sebbene non sia ancora universalmente disponibile senza un polyfill, il suo stadio avanzato indica che è molto probabile che diventi una parte standard di JavaScript. Gli sviluppatori possono iniziare a sperimentare con Temporal oggi utilizzando polyfill o abilitando funzionalità sperimentali nei loro ambienti di sviluppo del browser. L'adozione anticipata consente di essere all'avanguardia, comprenderne i benefici e integrarla nei propri progetti man mano che il supporto dei browser viene implementato.

La sua eventuale adozione diffusa ridurrà significativamente la necessità di librerie esterne di data/ora, fornendo una soluzione nativa e robusta per la gestione del tempo in JavaScript.

Migliori Pratiche per l'Uso di Temporal Duration

Per massimizzare i benefici di Temporal.Duration nelle tue applicazioni, considera queste migliori pratiche:

• Preferire Temporal.Duration.from(): Quando si creano durate da componenti noti o stringhe ISO, Temporal.Duration.from() con un oggetto letterale è spesso più leggibile e meno soggetto a errori rispetto agli argomenti posizionali del costruttore.
• Usare relativeTo per Confronti Ambigui: Fornire sempre un'opzione relativeTo quando si confrontano o si arrotondano durate che contengono anni, mesi o settimane. Ciò garantisce calcoli accurati fornendo il contesto del calendario necessario.
• Sfruttare until() e since(): Per calcolare l'intervallo tra due punti specifici nel tempo, preferire i metodi until() e since() sugli oggetti data-ora di Temporal. Essi gestiscono correttamente le complessità dei fusi orari e dell'ora legale.
• Normalizzare e Arrotondare per la Visualizzazione: Prima di presentare le durate agli utenti, considerare l'uso di normalize() e soprattutto di round() per convertire la durata nelle unità più appropriate e comprensibili (ad esempio, convertire 90 minuti in "1 ora e 30 minuti").
• Separare la Rappresentazione Interna dalla Visualizzazione: Mantenere precisi i calcoli interni della durata con Temporal.Duration. Trasformare e formattare per la visualizzazione solo durante il rendering dell'interfaccia utente, utilizzando funzioni di formattazione personalizzate e l'API Intl per una precisione globale.
• Rimanere Aggiornati: Tenere d'occhio i progressi dell'API Temporal e la compatibilità dei browser. Man mano che si avvicina alla standardizzazione completa, l'ecosistema si evolverà e potrebbero emergere nuovi strumenti o migliori pratiche.
• Essere Consapevoli della Precisione: Sebbene Temporal supporti la precisione al nanosecondo, utilizzare solo la precisione di cui si ha realmente bisogno. Una maggiore precisione può talvolta rendere più difficile il debug o portare ad arrotondamenti inaspettati durante la conversione a visualizzazioni a precisione inferiore.

Conclusione

L'introduzione di Temporal.Duration segna un significativo passo avanti per gli sviluppatori JavaScript che si confrontano con l'aritmetica degli intervalli di tempo. Fornendo un'API immutabile, esplicita e consapevole a livello globale, Temporal risolve le annose limitazioni del vecchio oggetto Date.

Ora è possibile eseguire con sicurezza calcoli temporali complessi, misurare accuratamente i periodi e presentare le durate in un modo che sia sia preciso che culturalmente appropriato per gli utenti di tutto il mondo. Che tu stia calcolando la durata di un ciclo di rilascio software, il tempo rimanente fino al lancio di un prodotto globale o l'età esatta di una persona, Temporal.Duration offre gli strumenti necessari per costruire applicazioni robuste e affidabili.

Abbraccia Temporal.Duration e trasforma il modo in cui gestisci il tempo nei tuoi progetti JavaScript. Il futuro della gestione di data e ora in JavaScript è qui, e promette un'esperienza di sviluppo più prevedibile, potente e globalmente compatibile.